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Preface 


Welcome to Qualys Cloud Platform! In this guide, we’ll show you how to install and use the 
Qualys Policy Compliance Scanning Connector to see your Qualys PC scan data in Jenkins. 


About Qualys 


Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and 
compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses 
simplify security operations and lower the cost of compliance by delivering critical security 
intelligence on demand and automating the full spectrum of auditing, compliance, and 
protection for IT systems and web applications. 


Founded in 1999, Qualys has established strategic partnerships with leading managed service 
providers and consulting organizations including Accenture, BT, Cognizant Technology 
Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT, Optiv, 
SecureWorks, Tata Communications, Verizon and Wipro. The company is also a founding 
member of the Cloud Security Alliance (CSA). For more information, please visit 
www.qualys.com 


Qualys Support 


Qualys is committed to providing you with the most thorough support. Through online 
documentation, telephone help, and direct email support, Qualys ensures that your questions 
will be answered in the fastest time possible. We support you 7 days a week, 24 hours a day. 
Access support information at www.qualys.com/support/ 
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Introduction to Qualys Policy Compliance Scanning Connector for 
Jenkins 


The Qualys Policy Compliance Scanning Connector empowers to automate the PC scanning of 
host and cloud instance from Jenkins. By integrating scans in this manner, Host or cloud 
instance security testing is accomplished to discover and eliminate security flaws. 


We'll help you: Install the Plugin | Configure the Plugin 


Install the Plugin 


You can install the Qualys Policy Compliance Scanning Connector from Jenkins. To install the 
Qualys Policy Compliance Scanning Connector, log into your instance of Jenkins and click 
Manage Jenkins. 


Jenkins 


E New Item 
& People 
> Build History 
L Project Relationship 


$=) Check File Fingerprint 


{Èt Manage Jenkins 
& My views 
À Credentials 


fm New View 


Next, click Manage Plugins. 


Jenkins 
= 


& Peopie Manage Jenkins 


Global Tool Configuration 
f Configure tools, their locations and automatic installers. 


wA. Jn N at 


# M Reload Configuration from Disk 
Discard all the loaded data in memory and reload everything from file system. Useful wig 


Manage Plugins 
Add, remove, disable or enable plugins that can extend the functionality of Jenkins 
A There are updates available 


do Mey 


| System Information 


= Displays various environmental information to assist trouble-shooting. 


If you are installing Qualys Policy Compliance Scanning Connector for the first time, click the 
Available tab and search for Qualys Policy Compliance Scanning Connector using the Filter bar. 
Select the plugin and click either Install without restart or Download now and Install after 
restart. After the plugin is installed, it will be listed in the Installed tab. 
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If the plugin is already installed in Jenkins and you want to update the Qualys Policy Compliance 
Scanning Connector, go to the Updates tab, search for the plugin and click Download now and 
Install after restart. 


That's it! The installation is now complete. Read on to learn about configuring the plugin. 


Prerequisites for Configuring the Plugin 


You must have a subscription to Qualys Policy Compliance and your Qualys Policy 
compliance account that you want to use for scanning the target host must have 
permission to access PC API. 


In your Qualys PC account, create an option profile with a name starting with Jenkins _‘ 
and add policies to this option profile for the Policy Compliance scan. In the Option 
Profile configuration section, the plugin will list only the option profiles that have a name 
starting with “Jenkins_”. 


Note that for selected option profiles, you need to select at least one policy for a 
successful scan launch. 


An authentication record for the target asset is required for the PC scan. If you already 

have an authentication record created for the host, the Scan API will use this record for 
scanning the host else you can use the plugin to create a new authentication record for 
the host. See Configure Scan Options in the guide. 


For the EC2 Instance scan, ensure your target instance is in the ‘Running’ state. Both the 
scanner appliance and EC2 connector that you have selected should be of the same 
account id (Users can see the account id in the drop-down field for EC2 connector and 
scanner on Qualys PC Scanning connector's configuration form). 


Currently, we support only Global Default Network. Ensure that your target scanners and 
hosts are placed under Global Default Network. 


Good to Know 


When the Jenkins Job with Qualys Policy Compliance Scanning connector stage is built for 
the first time, the Qualys Policy Compliance Scanning connector will - 


L 


Add a target asset (Host IP/EC2 Instance) into your Qualys subscription if not already 
present. 


The connector will then create an asset group with a name starting with 
Jenkins _AG_<Jenkins_project_name>. 


On successful creation of the asset group, the connector will then add the target asset 
into this newly created asset group 


The Qualys PC Scanning connector will attempt to create an authentication record using 
credentials selected by the user if no authentication record is found and the user have 
selected respective setting in Qualys PC Scanning connector's configuration. 


The connector will also add policies selected by the user in the configuration to the asset 
group created in the job. 
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On the subsequent run, Qualys Policy Compliance Scanning Connector will check if the asset 
group is present or not. If the asset group already exists, the plugin will simply overwrite the 
target asset and policies in it if at all they are changed in the connector configuration. 


Configure the Plugin for Pipeline projects 


Open your application’s pipeline project and click "Pipeline Syntax" to enter the Snippet 
Generator. 


Jenkins Demo4 


# Back to Dashboard 
| Status 

T> Changes 

@) Build Now 

© Delete Pipeline 

¥ Configure 

@, Full Stage View 


T> Rename 


Select "qualysPolicyComplianceScanner:Scan Host/Instances with Qualys PC" from the Steps 
drop-down menu. 


Steps 


Sample Step qualysPolicyComplianceScanner: Scan host/instances with Qualys PC v 
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Configure API Login 


Now you are ready to configure the plugin. The first step is to confirm that Jenkins can 
communicate to the Qualys Cloud Platform via the Qualys Policy Compliance (PC) API. You'll 
need valid account credentials for an active Qualys PC subscription. The account must have API 
access enabled as well as a role assigned with all necessary permissions. Qualys recommends 
using a service account restricted to API access only (no UI access) and having the least 
privileges possible. 


Select the Qualys platform/portal where your Qualys account resides and your account 
credentials for authenticating to the PC API server. Use the Add button to add account 
credentials in the Jenkins store for the new user. Once added, the credential is listed in the 
“Credentials” drop-down. 


Note that what you select here depends on the Qualys platform your organization is using. Learn 
more. 


If your Jenkins instance does not have direct Internet access and a proxy is required, click the 
"Use Proxy Settings" checkbox and enter the required information. 


API Login 


Provide details for accessing the Qualys Policy Compliance(PC) API 


Your Qualys Portal: US Platform 4 v 


* Credentials: Qualys_user/**** v PAPA 


D Use Proxy Settings 
Connection test successfull 


Click the "Test Connection" button. Assuming you have entered the correct API server URL for 
your subscription and the credentials are valid, you will see the message "Connection test 
successful!". 


Note that if your Qualys account resides on a private cloud platform, select “Private Cloud 
Platform” as your Qualys cloud platform, specify the API server URL and your account 
credentials to access the API. 


API Login 
Provide details for accessing the Qualys Policy Compliance(PC) API. 


Your Qualys Portal: Private Cloud Platform {v 


API Server URL: https://qualysapi.mycloud.com 


* Credentials: api_user/***** v| ae 


O Use Proxy Settings 
Connection test successfull 
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Configure Scan Options 


Next, either enter the host IP in your Qualys PC account or AWS EC2 Cloud Instance information 
that you wish to scan. You can also specify an environment variable for the Host IP and EC2 ID. 
Note that we currently support scanning only single IP or EC2 instance. 


Scan Options 
Provide information required to launch the scan 


* Scan Title: [job_name]_jenkins_build_[build_number] © 


Target 


Scan Host IP 


M 10.10.32.162 © 


O Scan EC2 instance 


By default, the PC scan name will be: 
[job_name]_jenkins_build_[build_number] + timestamp 


You can edit the scan name, but a timestamp will automatically be appended regardless. 


Optionally, to scan your assets residing on an EC2 cloud instance: 1) Provide the ID of Amazon 
EC2 Instance on which you want to launch the PC scan, 2) select the connector name for the 
instance. 


Scan Options 


Provide information required to launch the scan 


* Scan Title: [job_name]_jenkins_build_[build_number] © 


Target 


© Scan Host IP 


Scan EC2 instance 


* EC2 Instance Id: 


* EC2 Connector Name: Auto-EC2 Connector (Account Id: 


O Run selected EC2 connector 


When you select the “Run selected EC2 connector” check box, we run the EC2 connector to get 
the updated information about the instance only if the configured EC2 instace ID state is 
retumed as 'Unknown' by Qualys hostasset APIs. Post running the connector, scan launch 
attempt will be made only if the EC2 instance state is known. 


We call the “hostasset” API with the “Id” and “accountld” of the ec2 instance to get the 
region/endpoint details. 
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The Create Authentication Record step is optional. If you already have an authentication record 
for the host in your account, we will use that authentication record to authenticate to the host. 


In case the authentication record is not present for the host in your account, select Create 
Authentication Record and then select Windows or Unix platform. Click the Add button to add 
your host credentials, then select the credentials from the Credentials drop-down field. 


When the plugin will run, we will create an authentication record with the name 
Jenkins_windows_[Job Name] for windows or Jenkins_unix_[Job Name] for Unix based on the 
platform selection. 


Note that new authentication record creation from the plugin will fail if an authentication record 
for the target host already exists in your account. You need to delete the host authentication 
record from your account to create the new authentication record from the plugin. 


Create Authentication Record 


Platform Windows v 


Credentials: Qualys_user/**** {v e@Add v 


Next, configure scan parameters. 


* Scanner Name: Select the scanner appliance (Default - External) -@ 
MOR REONE Jenkins Initial PC Options M 


Select One or More Policies 
Select one or more desired policies for the PC scan. Qualys PC Scanning connector will evaluate result only for selected policies. 


RHEL 7.x 


» 


Scanner Name - Select the scanner appliance name from the drop-down that PC will use to scan 
your host assets on your network or on an EC2 instance to check the compliance of your systems 
against your policies. The default value is the “External” scanner if you do not select a scanner 
from the Scanner drop-down. 


Selecting the Host IP option will show you all the scanners including the scanners configured for 
scanning EC2 instances. When you select Cloud Instance (AWS EC2) option, we will show you 
only those scanners that are configured to scan EC2 instances. Select the appropriate scanner 
that is configured to scan your ec2 instance. 


Option Profile - The option profile contains the settings used for a compliance scan. Select the 
option profile and one or more policies for the PC scan. We show only the policies for the 
selected option profile. The plugin will evaluate the results for selected policies only. 


Note that option profiles and scanners may take a bit longer to populate after connection to the 
API server is successful. 
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Configure Scan Pass/Fail Criteria 


Next, configure the pass/fail criteria for a build. You can set any or all of the three conditions to 
fail the build. The three conditions are: 


Configure Scan Pass/Fail Criteria 


Set the conditions to fail the build job. The build will fail when ANY of the conditions are met. 


Fail by State AND Criticality 
By State 
Fail O Error O Exceptions 
By Criticality 
Serious Urgent Critical Medium Minimal 


Fail if Authentication Fails on Hosv/EC2 Instance 


O Exclude Conditions | 


Fail by State AND Criticality - This criterion lets you choose the states and the corresponding 
criticality to fail a build. The build will fail if both the state and the criticality condition is 
fulfilled. The build can be failed for all or any of these states for the controls you are evaluating: 
Fail, Error and Exceptions, and any or all of these criticalities: Serious, Urgent, Critical, Medium, 
and Minimal. 


Fail if Authentication Fails on Host/EC2 Instance - This criteria if selected will fail the build if the 
plugin fails to authenticate to the host IP or EC2 Instance using the authentication record. If this 
option is not selected and yet the authentication fails, we will pass the build but no reports will 
be generated. 


Exclude Condition - You can use the Exclude Conditions option to ignore specified CIDs or 
Control IDs while evaluating the policy for failure conditions. For example, we will not fail a 
build if an excluded CID is detected for a policy in the scan even if that CID meets the specified 
failure condition. We evaluate the Exclude conditions first and remove the CIDs that match the 
exclude conditions before evaluating the Failure Conditions. 


Timeout Settings 


scan status polling frequency and timeout duration for the scan. 


Timeout Settings 


Qualys PC Scan results will be collected per these settings. For each enter a value in minutes or an expression like 2*60 for 2 hours 


Frequency 

How often to check for scan result 2 minutes 
Timeout 

How long to wait for scan results 6072 minutes 


In the Timeout settings, specify the polling frequency in minutes for collecting the PC scan 
status data and the timeout duration for a running Jenkins build. The default value for polling 
frequency is 2 minutes and 120 minutes is the default timeout duration. 
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Next, click "Generate Pipeline Script”. This is your pipeline snippet for launching a PC scan. 


Generate Pipeline Script 


qualysPolicyComplianceScanner apiServer: 'https://qualysapi.mycloud.com’, createAuthRecord: true, credsid: 'US-POD-1-HostIP’, criticalityCritical: true, criticalityMedium: true, criticalityMinimal: true, 
criticalitySerious: true, criticalityUrgent: true, failByAuth: true, failByStateAndCriticality: true, hostlp: '0.0.0.0', optionProfile: ", platform: 'PCP", pollinginterval: '2', scanName: 
‘[job_name]_jenkins_build_[build_number]’, scannerName: ‘External’, selectedPolicies: '1485826::RHEL 7.x’, stateFail: true, unixAndWindowsCredentials: ‘windows’, unixAndWindowsCredentialsld: 
‘invalid_hostCreds', useHost: true, vulns Timeout: '60*2' 


The pipeline snippet is now ready to be plugged into your pipeline script. 


Configure the Plugin for Freestyle Projects 


As the configuration settings are the same as Pipeline Project, see “Configure the Plugin Pipeline 
Project” for detailed configuration. 


To create a Freestyle Project, click the Post-build Actions tab and Go to the Post-build Actions 
section. Select the Scan host/instances with Qualys PC option from the Add post -build action 
drop-down menu and then provide the following configuration details: 
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API Login 


Provide details for accessing the Qualys Policy Compliance(PC) API 


Your Qualys Portal US Platform 1 bd 


* Credentials Qualys_user/*** v 


O Use Proxy Settings 


Scan Options 


Provide information required to launch the scan 


* Scan Title test 


Target 
Scan Host IP 


“IP: 10.10.32.162 


O Scan EC2 instance 


O Create Authentication Record 


* Scanner Name: 7.5-scanner (Status: Offline) 


* Option Profile: Jenkins_1_OP 


Select One or More Policies 
EC2 i-0548f906c47648eab 
CentOS 7 3 

CentOs 7 2 

CentOS 7 1 


Configure Scan Pass/Fail Criteria 


Set the conditions to fail the build job. The build will fail when ANY of the conditions are met 


© Fail by State AND Criticality 
Fail if Authentication Fails on Host/EC2 Instance 


O Exclude Conditions 


Timeout Settings 


Qualys PC Scan results will be collected per these settings. For each enter a value in minutes or an expression like 2"60 for 2 hours. 
Frequency 
How often to check for scan result 2 minutes 
Timeout 
How long to wait for scan results 


60°2 minutes. 


Add post-build action + 


IN 


5 


6 


Test Connection 


CentOS7 4 CentOS 4 CentOS 4 CentOS 4 CentOS 4 CentOS 4 CentOS 4CentOS 4 CentOS 4 CentOS 4 CentOS 4 CentOS 4 CentOs 4 tS xs 
> 


© © © 


1) Provide your login 
account credentials to 
access the Qualys PC API 
server on the Qualys 
cloud platform. Select 
Use Proxy Settings to 
provide proxy 
information if your 
Jenkins server is behind 
a firewall. 


2) Click Test Connection 
to verify that the plugin 
can connect to the 
Qualys PC API server. 


3) Provide parameters: 
scan name, target host 
IPs, or AWS EC2 
information required to 
call the launch scan API. 


For Host/AssetIP and EC2 
Instance ID, you can also 
specify an environment 
variable in this format: 
env.{variable name} 


For example: 


f your environment 
variable name for Host IP 
is "hostIp" then the input 
for the Host IP field 
should be env.hostip. 


f your environment 
variable name for EC2 
nstance ID is "ec2Id" 
then the input for the 
EC2 ID field should be 
env.ec2Id. 


For PC plugin, only authentication record creation is optional. Scanner and Option profile with 


at least one policy are required parameters. 


Configure scan Pass/fail criteria. You can fail a build by state and criticality o 
authentication result. 


E 


the control and 


Provide data collection frequency and timeout duration for the running scan. 


Finally, click Save. 
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Qualys PC Scan Status 


Upon successful PC scan, Qualys PC Scanning connector will generate the scan report for the 
respective Jenkins build with link name 'Qualys PC Scan Report for <target_asset_ip>". After the 
scan completes, go to Qualys PC Scan Results. Click the Summary tab. The report has four 
sections: Results Summary, Scan Policies, Overall Compliance, Controls Causing Build Failure. 


The header of the result shows the scan’s ID, name, and the link to view the scan result in the PC 
module. The sections give you information on the total number of controls scanned for the 
selected policies along with the graphical break up of the number of controls with status as 
passed, failed, error, and exceptions. We also show the total number of controls that met the 
failure conditions, which caused the build to fail. 


The “Pass/Fail Criteria Results Summary section” shows in a matrix the count of failed, error, 
and exceptions controls found in the policy scan by their criticalities. 


4 Jenkins 


LIH 
aS 


Fail/E-ror Criteria Fenat Summary 


crnena tvateation urgent Senos caves vesum niama 


In the Summary tab, when you click a policy name in the “Scan Policies” section to view its 
details in a separate policy tab. In the policy tab, you will see the scan result for the selected 


policy. 
® Jenkins TEPE 


Fail/Errer Criteria Result Summary 
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Similarly, in the Summary tab when you click the count in the “Controls using build failures” 
section, we show you details of these controls in the “All Controls” tab. 


The “All Controls” tab gives the details of the scanned controls such as control’s ID, title, 
criticality, policy name, status, and unexpected values. You can filter the controls by their 
criticality and status. 


© or. Qualys Policy Compliance Results 


Show entries Show Only:  Criticality [All v] Status [All v| [Reset Filters | 
Summary 
All Controls Control ID Title Criticality Policy Title Status Unexpected Values Missing Values 
1071 Status of the 'Minimum Password Length' setting CRITICAL CentOS7&4 Passed NIA N/A 
1072 Status of the ‘Minimum Password Age' setting URGENT CentOS7&4 Passed N/A N/A 
1073 Status of the ‘Maximum Password Age' setting (e URGENT CentOS7&4 Passed N/A N/A 


xpiration) / Accounts having the ‘password never 
expires' flag set 


1091 Status of the number of days before a [Prompt us SERIOUS CentOS7&4 Passed N/A N/A 
er] password expiration warning prompt is display 
ed at login 

1117 Status of the ‘inetd’ or 'xinetd' service SERIOUS CentOS7&4 Passed N/A N/A 

1120 Status of the ‘klogin' service SERIOUS CentOS7&4 Passed N/A N/A 

1123 Status of the 'kshell' (Kerberos shell) service SERIOUS CentOS7&4 Passed N/A N/A 

1141 Status of the '[Locked/Unlocked] System Account URGENT CentOS7&4 Passed N/A N/A 
s and their default shells' 

1145 Current list of ‘Accounts having empty password f URGENT CentOS7&4 Passed N/A N/A 
ields' 

1159 List of accounts having 'root-level' privileges (UID URGENT CentOS7&4 Passed NIA N/A 
=0) 

Showing 1 to 10 of 100 entries Previous | 1 | 2 3 4 5 a 10 Next 
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Troubleshooting 


Test connection is successful but the Scanner, Option Profile, EC2 Connector drop-down 
fields on configuration are empty. 


This issue happens because your Qualys user account that you used to connect to the API server 
does not have permissions to access the PC APIs. To check the user's privileges: 


1. Login to the Qualys Platform using your account credentials and from the module picker, 


select the Administration module. 
2. On the User Management tab, search for the user by username. 


3. Select the user, and then select Actions > View to go to the User View screen. 


Administration v 


Users Action Log 


ET User Management User Management Role Management 


Create User w | 


m - 
| Edit | Modules First Name 

Edit Basic details CONS OS ES AUS E 
mS CS SDS CS 

Add Tags aw 0 ey 

Remove Tags cS 

Add Tags To Scope 
Owe ESS ES . 


Remove Tags From Scope 


Unassigned Business Unit 


4. Goto the Roles and Scopes tab and check if the user has access to PC APIs. 


User View: Ashish Kapoor x 
View Mode Click a role to view the permission assigned to that role 
User Details Assigned role(s) All Permissions 
Each role grants you a set of permissions that will apply to the objects you All parmissions granted across the 
Profile Settings nave access assigned roles 
A : 
mms al ==. 
CAAPI Access View Role UiAcceee 
Action Log CA Module Accuss: 
CAUI Access CAAPI Access Permission for 
subusers 
Account Activity PC User CA Ul Access Permission for 
subusors 
SCA User 
Access CA; 
SCANNER Accus Cloud Agent module 
PC Permissions: 
VH Usur PC Access 
PC Ul Access 
Scope 
Define what assets the user can access by tags 
Unassigned Busine 
Close 
oca 
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Jenkins Build console logs displays - "Data not found for policy "policy_name” and host 
<asset_ip>" 


The PC Scan API server returns this message in response to the API calls made by the Qualys PC 
Scanning Connector to fetch the PC scan data for the host asset. During the scan, if the Scan API 
discovers that the technology specified in the policy is not present on the target host, then no 
scan data is generated by the API for this policy after the scan. Hence, the message no data 
found for policy. 


For API to scan the host for the selected policy, ensure the technology that you have added to the 
policy is also present on the host 


Frequently Asked Questions (FAQ) 


What are the possible causes of a scan not getting launched resulting in build failure? 


Cause Build Status 


We will not launch the scan and abort the 
build with an appropriate error message. 
Qualys Policy Compliance Scanning 
Connector will try to launch the scan, but 
the build will fail as no alive hosts are 
found. 
We will not launch the scan and abort the 
build with an appropriate error message. 
Disabled Connector We recommend that you check the 
connector state and the scanner appliance 
status while configuring them. 


EC2 instance not found 


No host Alive 


What happens if the "Run selected EC2 connector” check box is selected? 


We will run the connector if the EC2 instance state is unknown and then launch the scan. Note 
that Qualys Policy Compliance Scanning Connector won't be able to run the connector if the 
connector is disabled. 


What happens if the "Run selected EC2 connector” check box is not selected? 


We directly run the scan if we have the instance information. 
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